/*
 * Copyright (c) 2021 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup Hitrace
 * @{
 *
 * @brief HiTraceMeter为开发者提供系统性能打点接口。\n
 *
 * 开发者通过在自己的业务逻辑中的关键代码位置调用HiTraceMeter系统跟踪提供的API接口，能够有效进行关键执行流程耗时度量和问题定位。\n
 *
 * HiTraceChain为开发者提供跨线程、跨进程的分布式跟踪能力。\n
 *
 * HiTraceChain支持在业务执行流程中，生成和传递唯一跟踪标识，在业务流程中输出的各类调试信息中（包括HiTraceMeter打点、应用事件、hilog日志等）记录该跟踪标识。\n
 * 在调试、问题定位过程中，开发人员可以通过该唯一跟踪标识将本次业务流程端到端的各类信息快速关联起来。\n
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 10
 */

/**
 * @file trace.h
 *
 * @kit PerformanceAnalysisKit
 * @include <hitrace/trace.h>
 *
 * @brief HiTraceMeter和HitraceChain模块接口定义，通过这些接口实现性能打点和分布式跟踪功能。\n
 *
 * 用户态trace格式使用竖线字符作为分隔符，所以通过HiTraceMeter接口传递的字符串类型参数应避免包含该字符，防止trace解析异常。\n
 * 用户态trace总长度限制512字符，超过的部分将会被截断。
 *
 * @library libhitrace_ndk.z.so
 * @syscap SystemCapability.HiviewDFX.HiTrace
 * @since 10
 */

#ifndef HIVIEWDFX_HITRACE_H
#define HIVIEWDFX_HITRACE_H

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief HiTraceId是否有效标志。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
typedef enum HiTraceId_Valid {
    /**
     * @brief 无效HiTraceId。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_ID_INVALID = 0,

    /**
     * @brief 有效HiTraceId。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_ID_VALID = 1,
} HiTraceId_Valid;

/**
 * @brief HiTrace版本号。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
typedef enum HiTrace_Version {
    /**
     * @brief 版本1。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_VER_1 = 0,
} HiTrace_Version;

/**
 * @brief HiTrace跟踪标志。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
typedef enum HiTrace_Flag {
    /**
     * @brief 缺省标志。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_FLAG_DEFAULT = 0,

    /**
     * @brief 异步调用标志。\n
     *
     * 设置该标志，同时跟踪同步和异步调用；缺省只跟踪同步调用。\n
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_FLAG_INCLUDE_ASYNC = 1 << 0,

    /**
     * @brief 无分支标志。\n
     *
     * 设置该标志，不创建分支信息；缺省创建分支信息。\n
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_FLAG_DONOT_CREATE_SPAN = 1 << 1,

    /**
     * @brief 埋点标志。\n
     *
     * 调试场景下设置该标志，调用信息埋点接口OH_HiTrace_Tracepoint()时，会打印埋点信息hilog日志；缺省不打印埋点信息hilog日志。\n
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_FLAG_TP_INFO = 1 << 2,

    /**
     * @brief 无开始结束信息标志。\n
     *
     * 调试场景下设置该标志，调用开始跟踪接口OH_HiTrace_BeginChain()和结束跟踪接口OH_HiTrace_EndChain()时，分别会打印开始、结束跟踪信息hilog日志；
     * 缺省不打印开始、结束跟踪信息hilog日志。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_FLAG_NO_BE_INFO = 1 << 3,

    /**
     * @brief 日志关联标志。\n
     *
     * 设置该标志，不会在hilog日志中附加HiTraceId信息；缺省会在hilog日志中附加HiTraceId信息。\n
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_FLAG_DONOT_ENABLE_LOG = 1 << 4,

    /**
     * @brief 故障触发标志。预置标志，暂未启用。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_FLAG_FAULT_TRIGGER = 1 << 5,

    /**
     * @brief 设备间埋点标志。HITRACE_FLAG_TP_INFO的一个子集，调试场景下使用。\n
     *
     * 当已设置HITRACE_FLAG_TP_INFO标志时，HITRACE_FLAG_D2D_TP_INFO标志不生效；\n
     * 当未设置HITRACE_FLAG_TP_INFO标志时，设置HITRACE_FLAG_D2D_TP_INFO标志，
     * 此时调用信息埋点接口OH_HiTrace_Tracepoint()，仅当mode参数为设备间通信HITRACE_CM_DEVICE的情况下，会打印埋点信息hilog日志。\n
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_FLAG_D2D_TP_INFO = 1 << 6,
} HiTrace_Flag;

/**
 * @brief 跟踪埋点类型枚举。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
typedef enum HiTrace_Tracepoint_Type {
    /**
     * @brief 客户端发送。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_TP_CS = 0,
    /**
     * @brief 客户端接收。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_TP_CR = 1,
    /**
     * @brief 服务端发送。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_TP_SS = 2,
    /**
     * @brief 服务端接收。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_TP_SR = 3,
    /**
     * @brief 通用类型，标识HITRACE_TP_CS、HITRACE_TP_CR、HITRACE_TP_SS、HITRACE_TP_SR四种场景之外的埋点。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_TP_GENERAL = 4,
} HiTrace_Tracepoint_Type;

/**
 * @brief 跟踪通信类型枚举。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
typedef enum HiTrace_Communication_Mode {
    /**
     * @brief 缺省通信类型。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_CM_DEFAULT = 0,
    /**
     * @brief 线程间通信。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_CM_THREAD = 1,
    /**
     * @brief 进程间通信。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_CM_PROCESS = 2,
    /**
     * @brief 设备间通信。
     *
     * @syscap SystemCapability.HiviewDFX.HiTrace
     *
     * @since 12
     */
    HITRACE_CM_DEVICE = 3,
} HiTrace_Communication_Mode;

/**
 * @brief HiTrace输出级别。
 *
 * 低于系统跟踪输出级别阈值的打点将不会生效。log版本阈值为HITRACE_LEVEL_INFO；nolog版本阈值为HITRACE_LEVEL_COMMERCIAL。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @atomicservice
 *
 * @since 19
 */
typedef enum HiTrace_Output_Level {
    /**
     * 仅用于调试的输出级别，优先级最低。
     *
     * @atomicservice
     *
     * @since 19
     */
    HITRACE_LEVEL_DEBUG = 0,
    /**
     * 用于log版本的输出级别。
     *
     * @atomicservice
     *
     * @since 19
     */
    HITRACE_LEVEL_INFO = 1,
    /**
     * 用于log版本的输出级别，优先级高于HITRACE_LEVEL_INFO。
     *
     * @atomicservice
     *
     * @since 19
     */
    HITRACE_LEVEL_CRITICAL = 2,
    /**
     * 用于nolog版本的输出级别，优先级最高。
     *
     * @atomicservice
     *
     * @since 19
     */
    HITRACE_LEVEL_COMMERCIAL = 3,
    /**
     * 输出级别范围限制。
     *
     * @atomicservice
     *
     * @since 19
     */
    HITRACE_LEVEL_MAX = HITRACE_LEVEL_COMMERCIAL,
} HiTrace_Output_Level;

/**
 * @brief HiTraceId定义。
 *
 * @struct HiTraceId
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
typedef struct HiTraceId {
#if __BYTE_ORDER == __LITTLE_ENDIAN
    /** HiTraceId是否有效。 */
    uint64_t valid : 1;
    /** HiTraceId的版本号。 */
    uint64_t ver : 3;
    /** HiTraceId的跟踪链标识。 */
    uint64_t chainId : 60;
    /** HiTraceId的跟踪标志位。 */
    uint64_t flags : 12;
    /** HiTraceId的分支标识。 */
    uint64_t spanId : 26;
    /** HiTraceId的父分支标识。 */
    uint64_t parentSpanId : 26;
#elif __BYTE_ORDER == __BIG_ENDIAN
    /** HiTraceId的跟踪链标识。 */
    uint64_t chainId : 60;
    /** HiTraceId的版本号。 */
    uint64_t ver : 3;
    /** HiTraceId是否有效。 */
    uint64_t valid : 1;
    /** HiTraceId的父分支标识。 */
    uint64_t parentSpanId : 26;
    /** HiTraceId的分支标识。 */
    uint64_t spanId : 26;
    /** HiTraceId的跟踪标志位。 */
    uint64_t flags : 12;
#else
#error "ERROR: No BIG_LITTLE_ENDIAN defines."
#endif
} HiTraceId;

/**
 * @brief 开始跟踪。\n
 *
 * 当前线程TLS（Thread Local Storage，线程本地存储）中不存在有效的HiTraceId时，生成有效的HiTraceId并设置到当前线程TLS中，返回该HiTraceId。\n
 * 当前线程TLS中已存在有效的HiTraceId时，不会开始新的跟踪，返回各属性值均为0的无效HiTraceId。\n
 *
 * @param name 跟踪业务名。
 * @param flags 跟踪标志组合，见{@link HiTrace_Flag}。
 * @return {@link HiTraceId}结构体。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
HiTraceId OH_HiTrace_BeginChain(const char *name, int flags);

/**
 * @brief 结束跟踪。\n
 *
 * 结束跟踪并将当前线程TLS中的HiTraceId设置为无效。\n
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_EndChain();

/**
 * @brief 获取跟踪标识。\n
 *
 * 获取当前线程TLS中的HiTraceId。\n
 *
 * @return {@link HiTraceId}结构体。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
HiTraceId OH_HiTrace_GetId();

/**
 * @brief 设置跟踪标识。\n
 *
 * 将给定的HiTraceId设置到当前线程TLS中。若给定的HiTraceId无效，则不执行任何操作。\n
 *
 * @param id 要设置的{@link HiTraceId}。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_SetId(const HiTraceId *id);

/**
 * @brief 清除跟踪标识。\n
 *
 * 将当前线程TLS中的HiTraceId设置为无效。\n
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_ClearId(void);

/**
 * @brief 创建跟踪分支。\n
 *
 * 创建一个HiTraceId，使用当前线程TLS中的chainId、spanId初始化HiTraceId的chainId、parentSpanId，并为HiTraceId生成一个新的spanId，返回该HiTraceId。\n
 *
 * @return {@link HiTraceId}结构体。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
HiTraceId OH_HiTrace_CreateSpan(void);

/**
 * @brief HiTraceMeter跟踪信息埋点。\n
 *
 * type为客户端发送CS和服务端接收SC时，进行同步HiTraceMeter开始打点；
 * type为客户端接收CC和服务端发送SS时，进行同步HiTraceMeter结束打点；
 * type为通用类型GENERAL时，不会进行HiTraceMeter打点。\n
 * type为客户端发送CS和客户端接收CC的信息埋点需配套使用；
 * type为服务端接收SC和服务端发送SS的信息埋点需配套使用。
 * 否则，HiTraceMeter开始与结束打点无法正常匹配。\n
 *
 * @param mode 跟踪通信模式，见{@link HiTrace_Communication_Mode}。
 * @param type 跟踪信息类型，见{@link HiTrace_Tracepoint_Type}。
 * @param id 实施信息埋点操作的{@link HiTraceId}。
 * @param fmt HiTraceMeter打点操作传入的trace说明信息的格式化字符串。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_Tracepoint(
    HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId *id, const char *fmt, ...);

/**
 * @brief 初始化HiTraceId。
 *
 * @param id 需要初始化的{@link HiTraceId}。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_InitId(HiTraceId *id);

/**
 * @brief 根据字节数组创建HiTraceId。
 *
 * @param id 需要创建的{@link HiTraceId}。
 * @param pIdArray 字节数组。
 * @param len 字节数组长度。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_IdFromBytes(HiTraceId *id, const uint8_t *pIdArray, int len);

/**
 * @brief 判断HiTraceId是否有效。
 *
 * @param id 需要判断是否有效的{@link HiTraceId}。
 * @return true：{@link HiTraceId}有效；false：{@link HiTraceId}无效。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
bool OH_HiTrace_IsIdValid(const HiTraceId *id);

/**
 * @brief 判断HiTraceId是否启用了跟踪标志flag。
 *
 * @param id 需要判断指定跟踪标志是否启用的{@link HiTraceId}。
 * @param flag 指定的跟踪标志，见{@link HiTrace_Flag}。
 * @return true：{@link HiTraceId}已启用flag；false：{@link HiTraceId}未启用flag。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag);

/**
 * @brief 启用HiTraceId中指定的跟踪标志。
 *
 * @param id 需要启用指定跟踪标志的{@link HiTraceId}。
 * @param flag 指定的跟踪标志，见{@link HiTrace_Flag}。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_EnableFlag(const HiTraceId *id, HiTrace_Flag flag);

/**
 * @brief 获取HiTraceId中设置的跟踪标志位。
 *
 * @param id 需要获取跟踪标志位的{@link HiTraceId}。
 *
 * @return {@link HiTraceId}中设置的跟踪标志位。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
int OH_HiTrace_GetFlags(const HiTraceId *id);

/**
 * @brief 设置跟踪标志位到{@link HiTraceId}中。
 *
 * @param id 需要设置跟踪标志位的{@link HiTraceId}。
 * @param flags 指定的跟踪标志位，见{@link HiTrace_Flag}。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_SetFlags(HiTraceId *id, int flags);

/**
 * @brief 获取HiTraceId中的跟踪链ID。
 *
 * @param id 需要获取跟踪链ID的{@link HiTraceId}。
 *
 * @return 跟踪链ID。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
uint64_t OH_HiTrace_GetChainId(const HiTraceId *id);

/**
 * @brief 设置跟踪链ID到HiTraceId中。
 *
 * @param id 需要设置跟踪链ID的{@link HiTraceId}。
 * @param chainId 需要设置的跟踪链ID。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId);

/**
 * @brief 获取当前HiTraceId中的分支ID。
 *
 * @param id 需要获取分支ID的{@link HiTraceId}。
 *
 * @return {@link HiTraceId}中设置的分支ID。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id);

/**
 * @brief 设置分支ID到HiTraceId中。
 *
 * @param id 需要设置分支ID的{@link HiTraceId}。
 * @param spanId 需要设置的分支ID。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId);

/**
 * @brief 获取当前HiTraceId中的父分支ID。
 *
 * @param id 需要获取父分支ID的{@link HiTraceId}。
 *
 * @return {@link HiTraceId}中设置的父分支ID。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id);

/**
 * @brief 设置HiTraceId结构的parentSpanId字符。
 *
 * @param id 需要设置父分支ID的{@link HiTraceId}。
 * @param parentSpanId 需要设置的父分支ID。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId);

/**
 * @brief 将HiTraceId转换为字节数组，用于缓存或者通信传递。
 *
 * @param id 需要转换的{@link HiTraceId}。
 * @param pIdArray 字节数组。
 * @param len 字节数组长度。
 *
 * @return 转换后的字节数组长度。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 *
 * @since 12
 */
int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len);

/**
 * @brief 标记一个同步跟踪耗时任务的开始。\n
 *
 * 同步跟踪打点接口OH_HiTrace_StartTrace()和OH_HiTrace_FinishTrace()必须配对使用。\n
 * OH_HiTrace_StartTrace()和OH_HiTrace_FinishTrace()函数对可以嵌套使用，跟踪解析时使用栈式数据结构进行匹配。\n
 * 从API version 19开始，建议使用OH_HiTrace_StartTraceEx()接口，以便分级控制跟踪输出。\n
 *
 * @param name 跟踪的名字。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 * @since 10
 */
void OH_HiTrace_StartTrace(const char *name);

/**
 * @brief 标记一个同步跟踪耗时任务的结束。\n
 *
 * 必须和OH_HiTrace_StartTrace()配对使用。跟踪解析时，和其前执行流程中最近的OH_HiTrace_StartTrace()进行匹配。\n
 * 从API version 19开始，建议使用OH_HiTrace_FinishTraceEx()接口，以便分级控制跟踪输出。\n
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 * @since 10
 */
void OH_HiTrace_FinishTrace(void);

/**
 * @brief 标记一个异步跟踪耗时任务的开始。\n
 *
 * 用于在异步操作前调用进行开始打点，异步跟踪开始和结束数据由于不是顺序发生的，所以解析时需要通过一个唯一的taskId进行识别。\n
 * 必须和OH_HiTrace_FinishAsyncTrace()配对使用，参数name和taskId相同的开始与结束打点相匹配，构成一个异步跟踪耗时任务。\n
 * 如果有多个相同name的任务需要跟踪或者对同一个任务跟踪多次，并且任务同时被执行，则每次调用的taskId需不相同。\n
 * 如果具有相同name的任务是串行执行的，则taskId可以相同。\n
 * 从API version 19开始，建议使用OH_HiTrace_StartAsyncTraceEx()接口，以便分级控制跟踪输出与跟踪聚类。\n
 *
 * @param name 异步跟踪的名字。
 * @param taskId 异步跟踪的ID。 异步跟踪开始和结束由于不是顺序发生的，所以需要通过name和每次执行唯一的taskId进行开始和结束的匹配。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 * @since 10
 */
void OH_HiTrace_StartAsyncTrace(const char *name, int32_t taskId);

/**
 * @brief 标记一个异步跟踪耗时任务的结束。\n
 *
 * 在异步操作完成后如回调函数中调用，进行结束打点。\n
 * 和OH_HiTrace_StartAsyncTrace()配对使用，参数name和taskId必须与异步跟踪的开始打点接口的对应参数值保持一致。\n
 * 从API version 19开始，建议使用OH_HiTrace_FinishAsyncTraceEx()接口，以便分级控制跟踪输出。\n
 *
 * @param name 异步跟踪的名字。
 * @param taskId 异步跟踪的ID。异步跟踪开始和结束由于不是顺序发生的，所以需要通过name和每次执行唯一的taskId进行开始和结束的匹配。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 * @since 10
 */
void OH_HiTrace_FinishAsyncTrace(const char *name, int32_t taskId);

/**
 * @brief 用于跟踪给定整数变量名和整数值。\n
 *
 * 多次执行该接口可以跟踪给定整数变量在不同时刻的数值变化。\n
 * 从API version 19开始，建议使用OH_HiTrace_CountTraceEx()接口，以便分级控制跟踪输出。\n
 *
 * @param name 整数变量跟踪的名字，不必与真实变量名相同。
 * @param count 整数值。
 *
 * @syscap SystemCapability.HiviewDFX.HiTrace
 * @since 10
 */
void OH_HiTrace_CountTrace(const char *name, int64_t count);

/**
 * @brief 标记一个同步跟踪耗时任务的开始，分级控制跟踪输出。\n
 *
 * 同步跟踪打点接口OH_HiTrace_StartTraceEx()和OH_HiTrace_FinishTraceEx()必须配对使用。\n
 * OH_HiTrace_StartTraceEx()和OH_HiTrace_FinishTraceEx()函数对可以嵌套使用，跟踪解析时使用栈式数据结构进行匹配。\n
 *
 * @param level 跟踪输出优先级。
 * @param name 同步跟踪的名字。
 * @param customArgs 键值对，多个键值对使用逗号分隔，例"key1=value1,key2=value2"。
 *
 * @atomicservice
 * @since 19
 */
void OH_HiTrace_StartTraceEx(HiTrace_Output_Level level, const char *name, const char *customArgs);

/**
 * @brief 标记一个同步跟踪耗时任务的结束，分级控制跟踪输出。\n
 *
 * 必须和OH_HiTrace_StartTraceEx()配对使用，参数level必须与同步跟踪的开始打点接口OH_HiTrace_StartTraceEx()的对应参数值一致。\n
 * 跟踪数据解析时，和其前执行流程中最近的OH_HiTrace_StartTraceEx()进行匹配。\n
 *
 * @param level 跟踪输出优先级。
 *
 * @atomicservice
 * @since 19
 */
void OH_HiTrace_FinishTraceEx(HiTrace_Output_Level level);

/**
 * @brief 标记一个异步跟踪耗时任务的开始，分级控制跟踪输出。\n
 *
 * 用于在异步操作执行前进行开始打点，异步跟踪开始和结束数据由于不是顺序发生的，所以解析时需要通过一个唯一的taskId进行识别。\n
 * 和OH_HiTrace_FinishAsyncTraceEx()配对使用，参数name和taskId相同的开始与结束打点相匹配，构成一个异步跟踪耗时任务。\n
 * 如果有多个相同name的任务需要跟踪或者对同一个任务跟踪多次，并且任务同时被执行，则每次调用的taskId需不相同。\n
 * 如果具有相同name的任务是串行执行的，则taskId可以相同。\n
 * 不同进程的taskId不会相互干扰。\n
 *
 * @param level 跟踪输出优先级。
 * @param name 异步跟踪的名字。
 * @param taskId 异步跟踪的ID。
 * @param customCategory 自定义聚类名称，用于聚合同一类异步跟踪打点。
 * @param customArgs 键值对，多个键值对使用逗号分隔，例"key1=value1,key2=value2"。
 *
 * @atomicservice
 * @since 19
 */
void OH_HiTrace_StartAsyncTraceEx(
    HiTrace_Output_Level level, const char *name, int32_t taskId, const char *customCategory, const char *customArgs);

/**
 * @brief 标记一个异步跟踪耗时任务的结束，分级控制跟踪输出。\n
 *
 * 用于在异步操作完成后进行结束打点，例如在回调函数中调用。\n
 * 和OH_HiTrace_StartAsyncTraceEx()配对使用，参数level、name和taskId必须与异步跟踪开始打点接口的对应参数值保持一致。\n
 *
 * @param level 跟踪输出优先级。
 * @param name 异步跟踪的名字。
 * @param taskId 异步跟踪的ID。
 *
 * @atomicservice
 * @since 19
 */
void OH_HiTrace_FinishAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId);

/**
 * @brief 标记一个跟踪的整数变量，分级控制跟踪输出。
 *
 * @param level 跟踪输出优先级。
 * @param name 整数变量的名称，不必与实际变量名相同。
 * @param count 整数值。
 *
 * @atomicservice
 * @since 19
 */
void OH_HiTrace_CountTraceEx(HiTrace_Output_Level level, const char *name, int64_t count);

/**
 * @brief 判断当前是否开启应用trace捕获。
 *
 * @return 使用hitrace命令行工具等方式开启采集时返回true。
 * 未开启采集或停止采集后返回false，此时调用HiTraceMeter性能跟踪打点接口无效。
 *
 * @atomicservice
 * @since 19
 */
bool OH_HiTrace_IsTraceEnabled(void);

#ifdef __cplusplus
}
#endif
/** @} */

#endif // HIVIEWDFX_HITRACE_H